home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / idl / nsIHttpChannel.idl < prev    next >
Text File  |  2006-05-08  |  12KB  |  297 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is Mozilla.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications.
  19.  * Portions created by the Initial Developer are Copyright (C) 2001
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *   Gagan Saksena <gagan@netscape.com> (original author)
  24.  *   Darin Fisher <darin@netscape.com>
  25.  *
  26.  * Alternatively, the contents of this file may be used under the terms of
  27.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29.  * in which case the provisions of the GPL or the LGPL are applicable instead
  30.  * of those above. If you wish to allow use of your version of this file only
  31.  * under the terms of either the GPL or the LGPL, and not to allow others to
  32.  * use your version of this file under the terms of the MPL, indicate your
  33.  * decision by deleting the provisions above and replace them with the notice
  34.  * and other provisions required by the GPL or the LGPL. If you do not delete
  35.  * the provisions above, a recipient may use your version of this file under
  36.  * the terms of any one of the MPL, the GPL or the LGPL.
  37.  *
  38.  * ***** END LICENSE BLOCK ***** */
  39.  
  40. #include "nsIChannel.idl"
  41.  
  42. interface nsIHttpHeaderVisitor;
  43.  
  44. /**
  45.  * nsIHttpChannel
  46.  *
  47.  * This interface allows for the modification of HTTP request parameters and
  48.  * the inspection of the resulting HTTP response status and headers when they
  49.  * become available.
  50.  *
  51.  * @status FROZEN
  52.  */
  53. [scriptable, uuid(9277fe09-f0cc-4cd9-bbce-581dd94b0260)]
  54. interface nsIHttpChannel : nsIChannel
  55. {
  56.     /**************************************************************************
  57.      * REQUEST CONFIGURATION
  58.      *
  59.      * Modifying request parameters after asyncOpen has been called is an error.
  60.      */
  61.  
  62.     /**
  63.      * Set/get the HTTP request method (default is "GET").  Setter is case
  64.      * insensitive; getter returns an uppercase string.
  65.      *
  66.      * This attribute may only be set before the channel is opened.
  67.      *
  68.      * NOTE: The data for a "POST" or "PUT" request can be configured via
  69.      * nsIUploadChannel; however, after setting the upload data, it may be
  70.      * necessary to set the request method explicitly.  The documentation
  71.      * for nsIUploadChannel has further details.
  72.      *
  73.      * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
  74.      */
  75.     attribute ACString requestMethod;
  76.  
  77.     /**
  78.      * Get/set the HTTP referrer URI.  This is the address (URI) of the
  79.      * resource from which this channel's URI was obtained (see RFC2616 section
  80.      * 14.36).
  81.      * 
  82.      * This attribute may only be set before the channel is opened.
  83.      *
  84.      * NOTE: The channel may silently refuse to set the Referer header if the
  85.      * URI does not pass certain security checks (e.g., a "https://" URL will
  86.      * never be sent as the referrer for a plaintext HTTP request).  The
  87.      * implementation is not required to throw an exception when the referrer
  88.      * URI is rejected.
  89.      *
  90.      * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
  91.      */
  92.     attribute nsIURI referrer;
  93.  
  94.     /**
  95.      * Get the value of a particular request header.
  96.      *
  97.      * @param aHeader
  98.      *        The case-insensitive name of the request header to query (e.g.,
  99.      *        "Cache-Control").
  100.      *
  101.      * @return the value of the request header.
  102.      * @throws NS_ERROR_NOT_AVAILABLE if the header is not set.
  103.      */
  104.     ACString getRequestHeader(in ACString aHeader);
  105.  
  106.     /**
  107.      * Set the value of a particular request header.
  108.      *
  109.      * This method allows, for example, the cookies module to add "Cookie"
  110.      * headers to the outgoing HTTP request.
  111.      *
  112.      * This method may only be called before the channel is opened.
  113.      *
  114.      * @param aHeader
  115.      *        The case-insensitive name of the request header to set (e.g.,
  116.      *        "Cookie").
  117.      * @param aValue
  118.      *        The request header value to set (e.g., "X=1").
  119.      * @param aMerge
  120.      *        If true, the new header value will be merged with any existing
  121.      *        values for the specified header.  This flag is ignored if the
  122.      *        specified header does not support merging (e.g., the "Content-
  123.      *        Type" header can only have one value).  The list of headers for
  124.      *        which this flag is ignored is an implementation detail.  If this
  125.      *        flag is false, then the header value will be replaced with the
  126.      *        contents of |aValue|.
  127.      *
  128.      * If aValue is empty and aMerge is false, the header will be cleared.
  129.      *
  130.      * @throws NS_ERROR_IN_PROGRESS if called after the channel has been
  131.      *         opened.
  132.      */
  133.     void setRequestHeader(in ACString aHeader,
  134.                           in ACString aValue,
  135.                           in boolean aMerge);
  136.  
  137.     /**
  138.      * Call this method to visit all request headers.  Calling setRequestHeader
  139.      * while visiting request headers has undefined behavior.  Don't do it!
  140.      *
  141.      * @param aVisitor
  142.      *        the header visitor instance.
  143.      */
  144.     void visitRequestHeaders(in nsIHttpHeaderVisitor aVisitor);
  145.  
  146.     /**
  147.      * This attribute is a hint to the channel to indicate whether or not
  148.      * the underlying HTTP transaction should be allowed to be pipelined
  149.      * with other transactions.  This should be set to FALSE, for example,
  150.      * if the application knows that the corresponding document is likely
  151.      * to be very large.
  152.      *
  153.      * This attribute is true by default, though other factors may prevent
  154.      * pipelining.
  155.      *
  156.      * This attribute may only be set before the channel is opened.
  157.      *
  158.      * @throws NS_ERROR_FAILURE if set after the channel has been opened.
  159.      */
  160.     attribute boolean allowPipelining;
  161.  
  162.     /**
  163.      * This attribute specifies the number of redirects this channel is allowed
  164.      * to make.  If zero, the channel will fail to redirect and will generate
  165.      * a NS_ERROR_REDIRECT_LOOP failure status.
  166.      *
  167.      * NOTE: An HTTP redirect results in a new channel being created.  If the
  168.      * new channel supports nsIHttpChannel, then it will be assigned a value
  169.      * to its |redirectionLimit| attribute one less than the value of the
  170.      * redirected channel's |redirectionLimit| attribute.  The initial value
  171.      * for this attribute may be a configurable preference (depending on the
  172.      * implementation).
  173.      */
  174.     attribute unsigned long redirectionLimit;
  175.  
  176.  
  177.     /**************************************************************************
  178.      * RESPONSE INFO
  179.      *
  180.      * Accessing response info before the onStartRequest event is an error.
  181.      */
  182.  
  183.     /**
  184.      * Get the HTTP response code (e.g., 200).
  185.      *
  186.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  187.      *         has been received (before onStartRequest).
  188.      */
  189.     readonly attribute unsigned long responseStatus;
  190.  
  191.     /**
  192.      * Get the HTTP response status text (e.g., "OK").
  193.      *
  194.      * NOTE: This returns the raw (possibly 8-bit) text from the server.  There
  195.      * are no assumptions made about the charset of the returned text.  You
  196.      * have been warned!
  197.      *
  198.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  199.      *         has been received (before onStartRequest).
  200.      */
  201.     readonly attribute ACString responseStatusText;
  202.  
  203.     /**
  204.      * Returns true if the HTTP response code indicates success.  The value of
  205.      * nsIRequest::status will be NS_OK even when processing a 404 response
  206.      * because a 404 response may include a message body that (in some cases)
  207.      * should be shown to the user.
  208.      *
  209.      * Use this attribute to distinguish server error pages from normal pages,
  210.      * instead of comparing the response status manually against the set of
  211.      * valid response codes, if that is required by your application.
  212.      *
  213.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  214.      *         has been received (before onStartRequest).
  215.      */
  216.     readonly attribute boolean requestSucceeded;
  217.  
  218.     /**
  219.      * Get the value of a particular response header.
  220.      *
  221.      * @param aHeader
  222.      *        The case-insensitive name of the response header to query (e.g.,
  223.      *        "Set-Cookie").
  224.      *
  225.      * @return the value of the response header.
  226.      *
  227.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  228.      *         has been received (before onStartRequest) or if the header is
  229.      *         not set in the response.
  230.      */
  231.     ACString getResponseHeader(in ACString header);
  232.  
  233.     /**
  234.      * Set the value of a particular response header.
  235.      *
  236.      * This method allows, for example, the HTML content sink to inform the HTTP
  237.      * channel about HTTP-EQUIV headers found in HTML <META> tags.
  238.      *
  239.      * @param aHeader
  240.      *        The case-insensitive name of the response header to set (e.g.,
  241.      *        "Cache-control").
  242.      * @param aValue
  243.      *        The response header value to set (e.g., "no-cache").
  244.      * @param aMerge
  245.      *        If true, the new header value will be merged with any existing
  246.      *        values for the specified header.  This flag is ignored if the
  247.      *        specified header does not support merging (e.g., the "Content-
  248.      *        Type" header can only have one value).  The list of headers for
  249.      *        which this flag is ignored is an implementation detail.  If this
  250.      *        flag is false, then the header value will be replaced with the
  251.      *        contents of |aValue|.
  252.      *
  253.      * If aValue is empty and aMerge is false, the header will be cleared.
  254.      * 
  255.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  256.      *         has been received (before onStartRequest).
  257.      * @throws NS_ERROR_ILLEGAL_VALUE if changing the value of this response
  258.      *         header is not allowed.
  259.      */
  260.     void setResponseHeader(in ACString header,
  261.                            in ACString value,
  262.                            in boolean merge);
  263.  
  264.     /**
  265.      * Call this method to visit all response headers.  Calling
  266.      * setResponseHeader while visiting response headers has undefined
  267.      * behavior.  Don't do it!
  268.      *
  269.      * @param aVisitor
  270.      *        the header visitor instance.
  271.      *
  272.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  273.      *         has been received (before onStartRequest).
  274.      */
  275.     void visitResponseHeaders(in nsIHttpHeaderVisitor aVisitor);
  276.  
  277.     /**
  278.      * Returns true if the server sent a "Cache-Control: no-store" response
  279.      * header.
  280.      *
  281.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  282.      *         has been received (before onStartRequest).
  283.      */
  284.     boolean isNoStoreResponse();
  285.  
  286.     /**
  287.      * Returns true if the server sent the equivalent of a "Cache-control:
  288.      * no-cache" response header.  Equivalent response headers include:
  289.      * "Pragma: no-cache", "Expires: 0", and "Expires" with a date value
  290.      * in the past relative to the value of the "Date" header.
  291.      *
  292.      * @throws NS_ERROR_NOT_AVAILABLE if called before the response
  293.      *         has been received (before onStartRequest).
  294.      */
  295.     boolean isNoCacheResponse();
  296. };
  297.